Excalibur PropertyList Control, Version 1.0

PropertyList version 1.0

Properties
Methods
Events

The IPropOwnerDrawSink Interface
About ExColorPicker...

Buying ExPropertyList


Properties

  • AllowEdit
    Used to completely disable any editing of the property list.

  • BackColor
    Returns/sets the background color of the control. Can be a literal color or a system color constant.

  • BorderStyle
    Returns/sets whether the control has a 3D border around it.

  • Enabled
    Returns/sets whether the control can respond to user-generated events.

  • Font
    Returns/sets the font that is used to paint the list's collection of items.

  • FontHeader
    Returns/sets the font that is used to paint header type items in the list.

  • ForeColor
    Returns/sets the control's text color for unselected items.

  • HighlightColor
    Returns/sets the color of the rectangle used to indicate the currently selected item.

  • HighlightText
    Returns/sets the color of the text for the currently selected item.

  • HoldDraw
    Determines whether the control will paint itself.

  • hWnd
    Read-only. Returns the window handle for the property list control.

  • Item
    Usage (get): sValue = prplst.Item(index)
    Usage (let): prplst.Item(index) = sValue
    Returns/sets the string displayed in the left-hand column of the property list control.

  • ItemData
    Usage (get): vValue = prplst.ItemData(index)
    Usage (let): prplst.ItemData(index) = vValue
    Returns/sets a user-defined value for the specified item.

  • ItemType
    Usage (get): nValue = prplst.ItemType(index)
    Usage (let): prplst.ItemType(index) = nValue
    Returns/sets the display/functional type of the specified item.

  • ListCount
    Read-only. Returns the number of items in the list.

  • LongestItem
    Read-only. Returns the width, in Twips, of the longest item in the first column.

  • MouseIcon
    Sets a custom mouse cursor for the control.

  • MousePointer
    Returns/sets the type of mouse pointer displayed when over the control.

  • ReadOnly
    Returns/sets whether the specified item can be edited by the user.

  • Selected
    Returns/sets the index of the currently selected item in the list.

  • TextFalse
    Returns/sets the string to display in a Boolean-valued item when the value is False.

  • TextTrue
    Returns/sets the string to display in a Boolean-valued item when the value is True.

  • TopIndex
    Returns/sets the scrollbar's thumb position to display the specified item as the first in the list.

  • Value
    Usage (get): sValue = prplst.Value(index)
    Usage (let): prplst.Value(index) = sValue
    Returns/sets the string displayed in the right-hand column of the property list control.


Methods

    (Only custom methods shown here)

  • Add
    Adds an item to the property list.

    Usage: Add(Name As String, _
    [Content As String], _
    [ReadOnly As Boolean], _
    [ItemType As ItemTypes], _
    [Index As Integer]    )

    Arguments:
    Name -

      The string displayed in the left-hand side of the property list.
    Content -
      Optional. The string displayed in the right-hand side; the value, which can be changed by the user. Defaults to nothing.
    ReadOnly -
      Optional. Specifies whether the user is able to edit the item being added. Defaults to False.
    ItemType -
      Optional. Specifies the filter applied to the item being added. Possible values are:
      - ExPropStringValue
      The default type. The item can hold any string of up to 255 characters.
      - ExPropNumericValue
      The item will hold an integer value. (i.e., no decimals or commas.) Cutting operations are not allowed, but copying is. Pasting operations are allowed if the clipboard holds a number.
      - ExPropBoolValue
      The item will hold a True/False value. A dropdown boolean list is automatically provided.
      - ExPropBrowseButton
      The item has a text field which cannot be edited, but a browse (...) button is provided. A modal form or dialog is generally shown upon clicking the browse button (see the Browse event).
      - ExPropOleColor
      The item holds a literal or system color. A color well is displayed next to the item's value showing the current color, and a dropdown color box is provided, from which the user can choose from literal or system colors.
      - ExPropCustomValue
      A dropdown list like the ExPropBoolValue style, but you provide your own custom values for the item in response to the NeedData event.
      - ExPropOwnerDraw
      The item is completely owner-drawn, both left and right columns. Given a handle to a device context (hDC), you can use GDI calls to paint within the specified area.
      - ExPropPropertyHeader
      Not editable, and only the Name parameter has meaning. This item paints the string specified in the Name parameter with the HeaderFont property. There is no dividing line down the center of this row.
    Index -
      Optional. Specifies the item's placement in the list. If this parameter is omitted, the item is added to the end of the list.

  • Clear
    Removes all items from the property list.
    This method has no parameters.

  • CommitPending
    Saves the editing transaction currently in progress (if any).
    This method has no parameters.

  • HideControls
    Hides all controls used to edit list items.
    This method has no parameters.

  • Remove
    Removes just one item from the property list.

    Usage: Remove(Index As Integer)

    Arguments:
    Index -

      The index of the item to remove from the property list.
  • SetOwnerDrawSink
    Sets an object that implements IPropOwnerDrawSink that the PropertyList uses for owner-drawn items.

    Usage: SetOwnerDrawSink( _
    odsSinkObject As IPropOwnerDrawSink)

    odsSinkObject can be any object that implements the IPropOwnerDrawSink interface in IPropOwnerDraw.tlb. To use owner-draw in the property list control, add this type library to your project through the References dialog and put the following line in your form:
    Implements IPropOwnerDrawSink


Events

    (Only custom events shown here)

  • Browse
    Event Browse(ByVal Name As String, _
    ByVal Index As Integer, _
    FillWith As String    )

    Fires when the user clicks the Browse button of an item.

    Parameters:
    Name

      The string that is displayed in the left-hand side of the property list.
    Index
      The index of the item whose Browse button was clicked.
    FillWith
      Change this string to what you want the new value of the property to be. Usually this is a filename, picture, or font name.

  • KeyPressEdit
    Event KeyPressEdit(KeyAscii As Integer(

    Occurs when the user presses a key in the property list's edit field. Parameters:
    KeyAscii

      The ANSI code of the key which was pressed.

  • NeedData
    Event NeedData(ByVal Index As Integer, _
    ListItems() As String    )

    Fires when the the property list needs the list of string values you want for an ExPropCustomValue item.

    Parameters:
    Index

      The index of the item to get the values for.
    ListItems()
      An empty array of strings. ReDim the array to the number of list items you want and set each array element to the desired values to make available to the user.

  • Scroll
    Event Scroll()

    Fires when the propertylist's scrollbar changes in position.

  • SelChange
    Event SelChange(OldSel As Integer, _
    NewSel As Integer    )

    Fires when the user changes the current selection in the propertylist.

    Parameters:
    OldSel

      The index of the item that was selected before the change.
    NewSel
      The index of the item that is now selected.

  • ValueChanged
    Event ValueChanged(ByVal Name As String, _
    ByVal Index As Integer, _
    ByVal NewValue As String, _
    Cancel As Boolean    )

    Fires when the property list control is about to commit the changes that a user made to a property.

    Parameters:
    Name

      The string that is displayed in the left-hand side of the property list.
    Index
      The index of the item whose value was changed.
    NewValue
      The string that the user attempted to assign to the property.
    Cancel
      When the ValueChanged event is fired this parameter is False. Changing it to True will prevent the user's changes from taking effect.


The IPropOwnerDrawSink Interface

The owner-draw capabilities of the PropertyList control require an object that implements this interface. This can be done by adding the IPropOwnerDraw.tlb file to your project through the References dialog, which is listed under "Excalibur PropertyList Owner-draw Interface" if the typelib has been registered, and adding the following line to the General Declarations section of a class module or form:

Implements IPropOwnerDrawSink

You can then use the SetOwnerDrawSink method of the PropertyList to enable owner-draw. Note that you will see adverse effects in the control if you add owner-draw items to it without setting the owner-draw sink object.

The interface also provides facilities to use your own control for the second column of the property list when your owner-drawn item is selected. This allows you to create items that use more than the color dropdown, combo box or textbox controls used in the built-in item types.
All controls that you add for owner-draw should be made children of the property list control.

IPropOwnerDrawSink Members

Certain parameters mean the same thing for each member of the interface. These parameters are:
- sPropListName
    The name you have given the property list control that is calling this method.
- nIndex
    The index of the item that the property list is referring to in the method.
The members of this interface are as follows:

Sub PropCommitPending(sPropListName As String)

    Occurs when a pending transaction in an owner-drawn item needs to be committed. A common action to take when this method is called is to set the Value property of the currently selected item.

Sub PropDrawItem(sPropListName As String, _
nIndex As Integer, _
bDrawActive As Boolean, _
DrawDC As Long, _
rctLeft As Long, rctTop As Long, _
rctRight As Long, rctBottom As Long)

    Occurs when an owner-drawn item needs to be repainted. You must paint both the left and right columns of the item specified in the nIndex parameter. Parameters are as follows:
      bDrawActive
        If True, draw the item in its selected state. Otherwise, the item should be drawn normally.
      DrawDC
        This is the handle to the device context that you need to draw on. This is not equal to PropertyList1.hDC, because the control uses a memory DC to paint the list before displaying it on the screen.
      rctLeft
        The position on the X plane where the drawing should begin in the first column.
      rctTop
        The position on the Y plane where the drawing should begin.
      rctRight
        The position on the X plane where the drawing should end in the second column.
      rctBottom
        The position on the Y plane where the drawing should end.
    The X position where the first column ends is equal to:
    (PropertyList1.LongestItem \ Screen.TwipsPerPixelX) + 1
    The X position where the second column begins should be:
    (PropertyList1.LongestItem \ Screen.TwipsPerPixelX) + 6

Sub PropHideCtrls(sPropListName As String)

    This member is called when you need to set the Visible property to False for all controls that you are using for owner-draw.

Sub PropPlaceCtrl(sPropListName As String, _
nIndex As Integer, _
rctLeft As Long, rctTop As Long, _
rctWidth As Long, rctHeight As Long)

    Occurs when an owner-drawn item has been selected. If you are using your own control for this item, you should place it in this procedure using the coordinates given. The caption and state of the control should be set as well, and also made visible. The control should be a child of the property list.
    Example code for the placement of a checkbox follows. The checkbox is a child of the property list control.

        chkOD.Caption = PropertyList1.Value(nIndex)
    If chkOD.Caption = "1 - Visible" Then
            chkOD.Value = 1
    Else
            chkOD.Value = 0
    End If
    chkOD.Move rctLeft, rctTop, rctWidth, rctHeight
    chkOD.Visible = True


Purchasing Excalibur PropertyList

The PropertyList control costs $35 US Dollars. You can send payment in the form of check or money order (international money orders are accepted) to:

Ben Baird
3533N. 3000E.
Twin Falls, ID 83301
USA

Make the payment out to "Ben Baird", and include an e-mail address where I can send the full license file to you.


Future Versions of ExPropertyList

If you have any suggestions for improvements for the next version of the Excalibur PropertyList control, please send them to Ben Baird at psyborg@cyberhighway.com. Suggestions are seriously considered and you may see them implemented in the next version.


The ExColorPicker Control

The ColorPicker is undocumented - mostly because it is being given away for free. Although the PropertyList will not function in a compiled EXE if you have not purchased the OCX, the ColorPicker needs to license to be used freely in your applications. It is to be used at your own risk.